chore(ai): Add check-code-attribution Claude Code skill#5401
chore(ai): Add check-code-attribution Claude Code skill#54010xadam-brown wants to merge 5 commits into
Conversation
0xadam-brown
force-pushed
the
chore/check-code-attribution-skill
branch
2 times, most recently
from
e5ea3f3 to
3a6b60d
Compare
📲 Install BuildsAndroid
|
This comment was marked as outdated.
This comment was marked as outdated.
|
|
||
| set -euo pipefail | ||
|
|
||
| SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" |
There was a problem hiding this comment.
Can we use license gradle plugin or another license checking tool to find/enforce this?
For example: https://github.com/hierynomus/license-gradle-plugin
There was a problem hiding this comment.
Ah, great question. But I don't think so b/c this PR is about validating attributions for vendored / copied / adapted code, rather than dependencies declared in our Gradle scripts.
My understanding is libraries like license-gradle-plugin only address the latter, and we already have the enforce-license-compliance workflow that does that sort of thing.
(After you posted your comment, I added a "Background" dropdown under "Motivation and Context" in the PR description, which captures my current understanding. Could be mistaken, of course, so correct me if I goofed or misread your question.)
There was a problem hiding this comment.
Yeah I think it will only help with the header part of the problem. The license-gradle-plugin scans files to make sure they have a license header. You can give specific excludes and includes paths as well as the header format.
It doesn't help with the THIRD_PARTY_NOTICES though.
There was a problem hiding this comment.
Gotcha – and thx for pointing me in the right direction. I took a look at the license-gradle-plugin and had a chat with Claude about it. It's in the dropdown.
tl;dr: we could consider using a library to expand our skill's functionality by generating canonical headers in cases where we've already detected an invalid header. But there doesn't seem to be a good fit for detecting invalid headers to begin with – and, as you mentioned, no library will help us keep the headers and THIRD_PARTY_CONTRIBUTIONS in lockstep.
That^^ suggests sticking with the current approach as a base (viz, detection + informing the developer of defects) and thinking about whether canonical header generation is worth the extra investment. I plan to extend the check-code-attribution skill so it can be run on CI in a follow-on PR. My vote would be to delay a deeper dive until then, but let me know if you think otherwise 👍.
Claude convo: Click to expand
Me:
What do you think about this comment: #5401 (comment)? Is it feasible to use the library runningcode mentions?
Claude:
The license-gradle-plugin is actually not a good fit, even for the header part:
- Diverse, non-uniform headers. The plugin is designed to enforce a single, uniform header across your codebase (e.g., "all .java files must have the Apache 2.0 Sentry copyright header"). Your attribution headers are different per file — each vendored file has its own library name, copyright holder, license type, and source URL. The plugin can't check for that.
- Detection is the hard problem. The core value of the skill is identifying which files are vendored/adapted in the first place (via heuristics + LLM judgment). license-gradle-plugin has no concept of this — it just checks/stamps headers on files you explicitly include.
- It would fight with your existing first-party headers. Line 115 of the script already notes that many first-party files carry the project's own license header. The plugin would struggle to distinguish "this file needs a third-party attribution header" from "this file correctly has our own header."
- Only covers Java/Kotlin. Your skill also scans shell scripts, config files, etc. — the Gradle plugin only operates within Gradle's source sets.
Me:
Taking a look the License Maven Plugin that underlies license-gradle-plugin (https://mathieu.carbou.me/license-maven-plugin/configuration/), could we use it (either the maven or gradle version) to generate attribution headers once we've identified a candidate attribution and determined it's invalid?
Ie, we use the find-attribution-candidates.sh to locate candidate attributions; we ask the LLM to identify invalid attributions among that group; and then we have the LLM add the invalid attribution's file to the maven/gradle plugin set for that license type. Finally, the skill runs the plugin to generate the attribution(s) as defined by the maven/gradle plugin and replace the invalid attribution(s).
Thoughts?
Claude:
Good creative thinking, but I don't think it works well in practice. Here's why:
The Gradle plugin can't do it. Since sentry-java is a Gradle project, license-gradle-plugin is the natural choice — but it only supports one header template with one set of properties globally. No licenseSets, no per-file properties. You'd need multiple custom tasks, one per vendored file.
The Maven plugin can, but... It supports licenseSets (multiple header templates, each with their own includes/properties) and even headerSections for finer-grained substitution. But integrating a Maven plugin into a Gradle build is awkward — you'd be shelling out to mvn or pulling in a Maven executor.
The deeper issue: the config is the attribution. To set up a licenseSet for a file, the LLM needs to know the library name, copyright holder, license type, and source URL — the exact same information that goes into the 4-line header comment. Writing a licenseSet XML/Gradle block is more work than just writing the header directly into the file. You'd essentially be duplicating the attribution in two places (build config + file header), creating a maintenance burden.
Where a plugin shines vs. where it doesn't:
- Plugin excels: stamping 500 files with the same Apache 2.0 Sentry copyright header
- Plugin struggles: stamping 10 files with 10 different headers (different library, copyright holder, license, URL each time)
Our problem is the second case. The LLM already has the information and can write the 4-line comment directly — adding a plugin intermediary just adds indirection and config maintenance for no quality gain.
I think your current approach (LLM identifies the problem, LLM fixes the header directly) is actually the right one. The plugin would be solving a problem we don't have.
Me:
Gtk. Are there other libraries besides the mvn license plugin and the https://github.com/hierynomus/license-gradle-plugin that could do either what runningcode wants or what I just suggested?
Claude:
Here's what's out there:
Best fit: REUSE tool (fsfe/reuse-tool)
Python CLI + GitHub Action. Purpose-built for exactly the vendored code scenario. You declare per-file/per-glob license and copyright in a REUSE.toml, and it can both lint (reuse lint) and stamp headers (reuse annotate). It's opinionated about SPDX format, but that's arguably a plus for standardization. Not Gradle-native though.
Runner-up: Apache SkyWalking Eyes (license-eye)
Go CLI + GitHub Action. Supports multiple header sections in .licenserc.yaml, each with different SPDX IDs and copyright owners mapped to different path globs. Can both check and fix. Closest to a "configure once, enforce in CI" solution with per-file customization.
Gradle-native options
- Yumi Gradle Licenser (dev.yumi.gradle.licenser) — Actively maintained, supports multiple license header rules evaluated per-file in definition order. Closest Gradle-native option to what you'd need.
- CadixDev Licenser (org.cadixdev.licenser) — Has matching() blocks for different headers on different file patterns, but lightly maintained.
Not a fit
- google/addlicense — Single header per invocation, no config file. You'd need to script multiple runs.
- johann-petrak/licenseheaders — Same limitation, single template per run.
My take
None of these solve the detection problem (finding which files are vendored). They all assume you already know which files need which headers. So they can't replace find-attribution-candidates.sh + LLM evaluation.
Where they could add value is as a CI enforcement layer: once attributions are established, a tool like REUSE or SkyWalking Eyes could verify in CI that headers haven't drifted. But your skill already does that verification, and it also handles THIRD_PARTY_NOTICES.md, which none of these tools touch.
Net: these tools solve adjacent problems well, but none of them cover the full scope of what the skill does. If you wanted to adopt one, REUSE is the most philosophically aligned — but it would be additive to the skill, not a replacement for any part of it.
0xadam-brown
changed the title
check-code-attribution Claude Code skill
Adds a check-code-attribution skill that verifies license headers + THIRD_PARTY_NOTICES.md entries for code copied or adapted from third parties. Reports any invalid headers and entries in the branch diff, along with suggestions for their correction. Implementation notes: - Uses a cheap-to-excute and easy-to-update script to detect attribution candidates (see find-attribution-candidates.sh). - Relies on the LLM for fuzzy tasks (viz, determining the adequacy of candidate attributions + generating suggestions). - Includes a shell-based test harness with 30 tests covering edge cases (see test-find-attribution-candidates.sh). --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0xadam-brown
force-pushed
the
chore/check-code-attribution-skill
branch
from
3a6b60d to
97e7c65
Compare
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
…-candidates script + minor LLM prompt updates
…te reasons + remove the gh api comment-cleanup block as it's a holdover from an earlier CI implementation + minor cleanup.
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit fdfe030. Configure here.
| if has_third_party_attribution "$CONTENT_FILE"; then | ||
| is_candidate=true | ||
| reasons+=("renamed file with attribution markers") | ||
| fi |
There was a problem hiding this comment.
Renamed files with stripped attribution silently skipped
Low Severity
The rename (R) branch only checks the current file content for attribution markers via has_third_party_attribution. If a file is renamed and its attribution header is completely stripped, and it's not in a vendor path, is_candidate stays false and the file is silently skipped. Unlike the M branch, which detects removed attribution via has_removed_attribution_lines on the diff, the R branch never examines the old file content, missing the regression.
Reviewed by Cursor Bugbot for commit fdfe030. Configure here.
2 participants
📜 Description
Adds a
check-code-attributionskill that verifies license headers + THIRD_PARTY_NOTICES.md entries for code copied or adapted from third parties. Reports any invalid headers and entries from the branch diff, along with suggestions for their correction. (See screenshot + manual test outputs below for examples.)Implementation notes
find-attribution-candidates.sh), esp as we eventually want to run this on CI.test-find-attribution-candidates.sh; executed manually).Co-authored-by: Claude Opus 4.6 (1M context) noreply@anthropic.com
💡 Motivation and Context
Third-party code attribution is a legal and compliance requirement. Currently, attribution correctness is only caught during manual code review. This skill automates detection of vendored code in branch diffs and can help us flag missing or incomplete attributions before a PR is merged.
Background: Click to expand
Sentry SDKs and third-party code
3 possible ways third-party code enters Sentry’s SDKs (including sentry-java):
1. Plain vanilla dependencies
2. Shaded code
3. Vendored code
All third-party code must be properly attributed, and licenses must be compatible with Sentry’s licensing policies.
Plain deps + shaded code: We run an
enforce-license-complianceGitHub workflow that applies a FOSSA check to all plain vanilla dependencies and our few shaded dependencies, which ensures their licenses are properly attributed and are compatible with Sentry’s licensing policies.Vendored code: Relies on a manual process where developers add attributions to files containing vendored code + include a corresponding entry is included in the THIRD_PARTY_NOTICES.md file that ships with the SDK. Developers are also responsible for ensuring license compatibility.
The criteria for what counts as a proper attribution of vendored code lives in the CODE_ATTRIBUTION_CRITERIA.md file under the heading “Third-Party Code Attribution”.
Goal of this PR: Create a skill that helps us properly attribute vendored code
Types of vendored code:
The skill introduced in this PR protects (1) from regression and identifies instances of (2). (Addressing (3) is out of scope – and is obviously non-trivial.)
Skill does not mandate that license headers exactly match the template from CODE_ATTRIBUTION_CRITERIA.md so long as all template fields are present.
That^^ lets us maintain our current, diverse header formats and remain relatively unopinionated going forward. Let me know if you think we should be strict about things, and I can update.
Screenshot of output
Very much on the fence about displaying false positives (included to be conservative, as they helped me identify LLM quirks as I developed; they should be rare regardless). Let me know if you disagree. Happy to update.
💚 How did you test it?
test-find-attribution-candidates.sh) which covers candidate detection, rename tracking, NOTICES entry matching, deleted files, generated code exclusions, and edge casesManual tests + output: Click to expand
Diff 1: Remove entire license header
Output 1
Required attribution field(s) removed:
Diff 2: Modify existing license header, but retain all required fields
Output 2
Vendored code detected (Apache Commons Collections) – verify that
THIRD_PARTY_NOTICES.mdreflects your updates.Diff 3: Modify existing license header by removing one or more required fields
Output 3
Required attribution field(s) removed:
Copyright (C) 2016 Matej Tymeswas removed from the license header. Please restore it.Diff 4: Leave existing license header unchanged, but make an inconsistent modification to THIRD_PARTY_NOTICES.md entry
Output 4
Entry metadata inconsistent with source file headers:
THIRD_PARTY_NOTICES.md, but the source files (QueueFile.java,FileObjectQueue.java,ObjectQueue.java) all still say "Copyright (C) 2010Square, Inc."
Diff 5: Leave existing license header unchanged, but remove THIRD_PARTY_NOTICES.md entry
Output 5
Source file(s) still reference this library:
-
io.sentry.android.core.SentryShakeDetectorstill contains attribution header for Square's Seismic. Either restore theTHIRD_PARTY_NOTICES.mdentry or remove the vendored code.Diff 6: Add newly-vendored code with valid license header and THIRD_PARTY_NOTICES.md entry
Output 6
Vendored code detected (Dropwizard Metrics SlidingWindowReservoir) – verify that
THIRD_PARTY_NOTICES.mdreflects your updates.Diff 7: Add newly-vendored code with valid license header but no THIRD_PARTY_NOTICES.md entry
Output 7
Vendored code detected (Caffeine Cache) — attribution header is complete.
THIRD_PARTY_NOTICES.md. An entry needs to be added.Diff 8: Add newly-vendored code with an invalid license header and existing THIRD_PARTY_NOTICES.md entry
Output 8
Vendored code detected (Resilience4j RateLimiter) — missing required fields:
Copyright 2019 Robert Winkler and Bohdan StorozhukandLicensed under the Apache License, Version 2.0(per the existing
THIRD_PARTY_NOTICES.mdentry).Diff 9: Add newly-vendored code with an invalid license header and no THIRD_PARTY_NOTICES.md entry
Output 9
Vendored code detected (Guava RateLimiter) — missing required fields:
THIRD_PARTY_NOTICES.md. An entry needs to be added for Guava RateLimiter.Diff 10: Add newly-vendored code with an invalid license header, no THIRD_PARTY_NOTICES.md entry, and a new license type
Output 10
Vendored code detected (compact-writer) — missing required fields:
THIRD_PARTY_NOTICES.md. An entry needs to be added.THIRD_PARTY_NOTICES.md. Please verify it is compatible with Sentry's licensing policies:https://open.sentry.io/licensing/.
Diff 11: False positive
+---
+
+## Eclipse Collections — CircularArrayList (EPL 2.0)
+
+Source: https://github.com/eclipse/eclipse-collections/blob/master/eclipse-collections/src/main/java/org/eclipse/coll
ections/impl/list/mutable/CircularArrayList.java
+License: Eclipse Public License 2.0
+Copyright: Copyright (c) 2022 Goldman Sachs and others
+
+### Scope
+
+The Sentry Java SDK includes an adapted circular buffer implementation from Eclipse Collections. The code resides in
io. sentry.util.CircularBuffer.+
+```
+Copyright (c) 2022 Goldman Sachs and others.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0.
+
+SPDX-License-Identifier: EPL-2.0